AD-AU3  Ml 
UNCLASSIFIED 


DAVID  V  TAYLOR  NAVAL  SHIP  RESEARCH  ANO  DEVELOPMENT  CE— ETC  F/t  S/S 
AN  INTRODUCTION  TO  THE  '-ME'  MACROS  USED  WITH  NR OFF  ON  THE  VAX  — CTC(U) 
MAR  M  0  J  HIBSERT 
DTNSRDC/CMLD-M-07 


NL 


I 


00 

I 

o 


o 


DAVID  W.  TAYLOR  NAVAL  SHIP 
RESEARCH  AND  DEVELOPMENT  CENTER 


Bathaida,  Maryland  20084 


iH  < 
Ttn 
LO 

co 


o 

oo 


x 

< 

<u 

sz 


u. 

o 

CC 

z 


■o 

a> 

in 

=3 

\n 

O 

u 

u 

ro 

Z 


AN  INTRODUCTION  TO  THE 
"-ME"  MACROS  USED  WITH 
NROFF  ON  THE  VAX  11/780 


by 

Dabney  J.  Hibbert 


APPROVED  FOR  PUBLIC  RELEASE:  DISTRIBUTION  UNLIMITED 


>- 

Q- 

O 

C-3 


a> 

j= 


u 

3 

“O 

o 

u 


C 


Computation,  Mathematics  and  Logistics  Department 
Departmental  Report 


NOW  DTNSRDC  5602/30  (2-60) 
(tupenadn  3860/46) 


82  04  15  062 


MAJOR  DTNSRDC  ORGANIZATIONAL  COMPONENTS 


GP  0  866  907 


NDW-DTNSRDC  MO 2/21  (2-OW 


Unclassified 


SECURITY  CLASSIFICATION  OF  This  PACE  (Whan  Data  Entarad) 


REPORT  DOCUMENTATION  PAGE 


ii 


EPORT  NUMBER 


CMLD-82-07 


4.  TITLE  (and  Subtitle) 

An  Introduction  to  the  "-ME11  macros  used 
with  NROFF  on  the  VAX  11/780 


READ  INSTRUCTIONS 
BEFORE  COMPLETING  FORM 


i  RECIPIENT'S  CATALOG  NUMBER 


C.  PERFORMING  ORG.  REPORT  NUMBER 


7.  authorc*; 


8.  CONTRACT  OR  GRANT  NUMBERO) 


Dabney  J.  Hibbert 


»■  PERFORMING  ORGANIZATION  NAME  ANO  ADDRESS 

David  W.  Taylor  Naval  Ship  RSD  Center 
ADP  Software  Specialist  (Code  1 89 - 1 ) 
Bethesda.  Maryland  20084  _ 


II.  CONTROLLING  OFFICE  NAME  AND  AOORESS 


10.  PROGRAM  ELEMENT.  PROJECT.  TASK 
AREA  *  WORK  UNIT  NUMBERS 


I 


12.  REPORT  DATE 

March  1982 


13-  NUMBER  OP  PAGES 

33  _ _ 


MONITORING  AGENCY  NAME  A  ADDRESS///  different  from  Controlling  Offlca)  IS.  SECURITY  CLASS,  (of  thla  roport) 

Unclassified 


15  a.  DECLASSIFICATION/ DOWNGRADING 
SCHEDULE 


16.  DISTRIBUTION  STATEMENT  (of  thla  Roport) 


Approved  for  Public  Release:  Distribution  Unlimited 


17.  DISTRIBUTION  STATEMENT  (ol  tha  abstract  entered  In  Block  20,  II  dlffarant  Irom  Report) 


19.  KEY  WORDS  (Continua  on  ravaraa  alda  tl  nacaaamry  and  tdantlly  by  block  numbar) 


Text  processing,  memorandum  macro  instructions,  macro  instruct  .s, 

UNIX,  NROFF,  input  file,  headers,  footers,  lists,  displays,  delayed  text. 


RACT  (Continua  on  ravaraa  alda  It  nacaaaary  and  laantlfy  by  block  nunbar) 

This  document  gives  document  preparation  users  a  brief  introduction  to 
and  provides  some  examples  of  ""ME"  macros,  a  general  purpose  package 
of  text  formatting  macros  used  with  the  UNIX  text  formatter,  "NROFF". 
These  macros  provide  a  flexible  tool  for  producing  many  common  types  of 
documents. 


DO  ,  ^:M7,  1473 


EDITION  OF  I  NOV  88  IS  OBSOLETE 
S/N  010  2*014*  860 1 


Unclassified 


SECURITY  CLASSIFICATION  OF  THIS  PAGE  | 


ns  taiarad) 


SECUNlTY  CLASSIFICATION  OF  THIS  FAOEfWi**  DM*  Int*r*« 


TABLE  OF  CONTENTS 


Page 


ABSTRACT . 1 

PURPOSE . 1 

DIFFERENCES  BETWEEN  KROFF  MACRO  PACKAGES  ON  THE  VAX 

fits D  CN  THE  11/70 . 1 

MANUALS  USEFUL  FOR  DOCLfvENT  PROCESSING . 3 

GUIDELINES  FOR  TEXT  PROCESSING . 4 

BASIC  INSTRUCTIONS . 6 


PARAGRAPHS .  .  . 
PAGE  LAYOUT. . 
Spac i ng .  . 
Centering 


HEADERS  &  FOOTERS . 7 

DISPLAYS . 9 


Lists . 9 

Keeps . 10 

Quotes . 11 

Centered  Blocks . 11 

SPECIAL  PARAGRAPHS . 12 


Block  Style  Paragraphs . 12 

Exdented  Paragraphs . 12 

Numbered  Paragraphs . 14 


ADVANCED  INSTRUCTIONS 


15 


SECTION  HEADINGS . 

Au t oma t i c a  1 1 y  Numb ered  Headings. 
Unnumbered  Headings . 


Accession  For 


•ins*  •(***« 

•wicta'b*  •  * 

Unannounced  q 
Justification 


Distribution/ 


Availability  Codes 
[Avail  and/or 
Special 


[Dlst 


15 

15 

15 


vj  Ov  Os  On 


DELAYED  TEXT . 16 

Footnotes . 16 

Re  ferences . 17 

Indexes . 18 

CDLLMsED  OUTPUT . 19 

OTHER  DOCLNtNT  CCMvWsDS . 22 

SAMPLE  NROFF  DOCUMENT . 24 


LIST  OF  FIGURES 

1  -  Comparison  of  Functions  of  hRDFF  Macro  Packages 

on  the  11/70  and  the  VAX . 2 

2  -  Sample  Text  for  2-Columned  Output . 20 

3  -  Sample  2 -Column  Output 


-i  i  - 


ABSTRACT 


This  document  gives  document  preparation  users  a  brief 
introduction  to  and  provides  some  examples  of  "-me"  macros, 
a  general  purpose  package  of  text  formatting  macros  used 
with  the  LNIX  text  formatter,  NROFF.  These  macros  provide  a 
flexible  tool  for  producing  many  common  types  of  documents. 


PURPOSE 


This  document  describes  the  text  processing  facilities 
available  on  the  UNIX[*]  operating  system  on  the  DEC  VAX 
11/780  via  the  NROFF[*]  text  formatter  and  its  -me  macro 
package!**].  This  document  will  also  attempt  to  show  the 
major  differences  between  the  -me  macro  package  and  the  -mm 
macro  package,  which  was  used  on  the  DEC  11/70. 

NROFF,  a  computer  program  that  runs  under  the  UNIX 
operating  system,  reads  an  input  file  prepared  by  the  user 
and  outputs  a  formatted  document.  The  input  file  consists 
of  both  text  and  macro  instructions,  which  indicate  to  the 
NROFF  program  how  the  user  wishes  the  output  to  be  format¬ 
ted. 


DIFFERENCES  BETWEEN  NROFF  MACRO  PACKAGES 
ON  THE  VAX  AND  CN  THE  11/70 


There  are  differences  between  most  of  the  NROFF 
memorandum  macro  instructions  used  on  the  DEC  11/70  as  com¬ 
pared  to  those  used  on  the  VAX  11/780.  For  those  users  who 
have  used  NROFF  and  its  associated  memorandum  macros  (i.e., 
the  "-mm"  option)  on  the  DEC  11/70,  Figure  1  should  prove  to 
be  a  useful  quick  reference  guide.  This  figure  presents  a 
comparison  chart  detailing  the  more  commonly  used  NROFF 
instruction  macros  as  used  on  both  the  11/70  and  the  VAX 
11/780. 


[*]UNIX  and  NROFF  are  Trademarks  of  Bell  Laboratories 
f ** ]De ve 1  oped  at  the  University  of  California,  Berkeley 
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MANUALS  USEFUL  FOR  DOCUMENT  PROCESSING; 


( 1 )  NROFF/TROFF_  y££i:s_  Manual  -  This  is  an  assembly 
language  level  manual  and  should  be  used  by  those  who 
want  to  change  existing  macros  or  write  new  ones. 

(2)  Wr  ui2_Pa£er  s_w^lt  h_NROFF_Ujn  ntj_-ME  -  Good  reference 
manual  that  contains  examples. 

(3)  i:^_R£!£££!2ce_Ma n u a  1  -  Quick  reference  manual  for  the 
memorandum  macros. 


GUIDELINES  FOR  TEXT  PROCESSING 


Because  NROFF  is  a  text  formatter,  it  is  responsible 
for  formatting  the  text.  That  is,  NROFF  collects  words  from 
the  input  lines  and  fills  the  output  lines,  justifying  the 
right  hand  margin  by  inserting  extra  spaces  in  the  line.  In 
addition,  NROFF  will  perform  more  complex  tasks  for  the 
user,  such  as  automatically  nurhbering  pages  and  skipping 
over  page  folds  on  a  printer  device.  NROFF  will  also  handle 
footnote  placement,  index  preparation,  and  reference  quota¬ 
tions.  The  following  lists  a  few  basic  guidelines  for  text 
process ing. 


1.  All  instructions  to  NROFF  (macro  instructions)  are 
placed  on  a  separate  l^ne  within  the  text  and  are  pre¬ 
ceded  by  a  (periodT. 


2.  It  is  recorrmended  that  those  preparing  input  text 
follow  the  suggestions  below: 

(a)  Begin  each  new  sentence  on  a  separate  line, 
since  eonrmon  corrections  are  to  add  or  delete  sen¬ 
tences. 

(b)  Do  not  put  spaces  at  either  the  beginning  or 
the  end  of  lines. 

(c)  Do  not  hyphenate  words  at  the  end  of  lines. 

(d)  Do  not  break  words  that  should  have  hyphens  in 
them  (such  as  mother-in-law)  over  a  line  -  instead, 
start  a  new  line  before  the  word. 

3.  An  example  of  the  above  rules  is  given  below: 

•PP 

The  project  team  approach  allows  for  better 
dissemination  of  technical  and  status  information. 
This  approach  also  allows  for  a  certain  amount  of 
on-the-job  training  when  a  team  consists  of  both 
trainee  and  journeyman  personnel. 

.  sp2 

The  above  input  lines  will  be  formatted  by  NROFF  and 
will  produce  the  following  output: 

The  project  team  approach  allows  for  better  dissemina¬ 
tion  of  technical  and  status  information.  This  approach 
also  allows  for  a  certain  amount  of  on-the-job  training  when 


a  team  consists  of  both  trainee  and  journeyman  personnel 


4.  After  the  input  file  (consisting  of  document  text 
and  macro  instructions)  is  ready  to  be  output,  the  user 
calls  the  NROFF  formatter  by  the  conrmands 

nroff  -me  ^ou r _f 

This  corrmand  will  display  the  formatted  text  on  your 
CRT  screen.  To  have  the  document  printed  on  a  printer 
device,  (such  as  a  Diablo  1650  or  a  LA120),  the  follow¬ 
ing  corrmand  is  used: 

nroff  -me  1  ca  t  -d 
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BASIC  INSTRUCTIONS 


PARAGRAPHS 

Paragraphs  are  begun  by  using  the  ".pp"  instruction. 
For  example,  the  input: 


■PP 

Now  is  the  time  for  all  good  men 
to  come  to  the  aid  of  their  country. 

will  produce  a  blank  line  followed  by  an  indented  (5  spaces) 
first  line.  The  result  is: 

Now  is  the  time  for  all  good  men  to  come  to  the  aid  of 
the i r  count ry . 


PAGE  LAYOUT 


Spac i ng 


B1 ank  Lines.  To  insert  blank  lines  in  the  text  where 
desired,  the  instruction: 

.  sp  N 

leaves  N  lines  of  blank  space.  When  N  is  omitted,  a  single 
blank  line  is  inserted. 


Doubie  Spacing .  NROFF  will  automatically  double  space  the 
output  text  with  the  instruction: 

.Is  2 

The  instruction  ".Is  1"  will  revert  back  to  the  single 
spaced  mode.  NoTe:  The  default  is  single  spacing. 

Br^eak  Page.  Usually,  NROFF  determines  when  to  start  a  new 
page.  To  start  a  new  page  when  desired  (i.e.,  not  at  the 
default  bottom  of  the  page  breaking  point),  the  instruction: 

.  bp 


can  be  used. 


iQSl®Elii2!2*  To  indent  the  left  hand  margin  further  than 
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default,  the  instruction: 


•  in  +N 

can  be  used,  where  N  is  the  number  of  spaces  you  would  addi¬ 
tionally  like  the  margin  to  be  indented.  To  return  the  mar¬ 
gin  size  to  the  original  number  of  spaces,  use  the  instruc¬ 
tion: 


•  in  -N 


Tem£££ar^  J_nde n£j_on .  For  a  temporary  indent,  the  instruc¬ 
tion: 


.  t  i  +N 

can  be  used.  With  the  use  of  this  instruction,  the  indenta¬ 
tion  applies  to  the  next  line  onj_^,  after  which  it  reverts 
to  the  previous  amount  of  indention. 


Center  i  ng 


Text  lines  can  be  centered  by  using  the  instruction: 

.  ce  N 

where  N  is  the  following  number  of  lines  that  are  to  be  cen¬ 
tered.  When  N  is  omitted,  only  the  line  following  the  ".ce" 
instruction  will  be  centered  horizontally  on  the  page. 


HEADERS  AND  FOOTERS 


As  desired,  headers  and  footers  can  be  defined,  which 
will  be  printed  at  the  top  and  bottom  of  every  page.  Within 
each  header  or  footer,  up  to  three  parts  may  be  defined, 
that  is,  (1)  a  1  e f t - j u s t  i  f  i  ed  part,  (2)  a  centered  part,  and 
(3)  a  r igh t - j us t i f i ed  part.  When  defining  these  parts 
within  the  headers  and  footers,  a  single  quote,  is  used 

to  separate  each  part.  If  the  user  does  not  desire  to 
define  his  own  headers  and  footers,  the  default  is  the 
current  page  number  centered  at  the  top  of  each  page. 

The  format  of  the  heade£  definition  macro  is: 

•  he  'left 'center 'r  ight  ' 
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and  the  format  of  the  footer  definition  macro  is: 

•  fo  '  le ft  'center  '  r  igh t ' 

There  are  several  predefined  strings  of  characters  that  the 
user  may  use  in  the  header  and  footer  instructions.  These 
ar  e : 

\*(dw  -  The  day  of  the  week,  as  a  word. 

\n(dy  -  The  day  of  the  month  (numeric). 

\*(mo  -  The  month,  as  a  word. 

\n(mo  -  The  month  of  the  year  (numerical). 
\n(yr  -  The  last  two  digits  of  the  current 
year . 

\*(td  -  Today's  date,  in  the  format  month 

(as  a  word),  day,  year. 

Some  useful  examples  follow: 

1.  For  a  blank  header: 

.he  - 


2.  For  a  centered  current  page  number,  either: 

.he  "%" 
or 

.fo  "%" 

Note  that  the  "%"  in  the  above  instructions  will  be 
replaced  with  the  current  page  number  when  it  is  out- 
pu  t . 

3.  For  a  centered  current  page  number,  the  current 
date  (month, day , year )  on  the  right,  and  "DRAFT"  on  the 
left,  all  at  the  top  of  every  page: 

.he  'DRAFT  '%'\*( td ' 

This  instruction  would  be  output  as: 

CRAFT  -1-  February  13,  1982 


4.  For  a  centered  current  page  number  surrounded 
by  dashes,  "FINAL"  on  the  left,  and  the  date  (rrm/dd/yy) 
on  the  left,  alt  at  the  bottom  of  every  page: 

.fo  'FINAL '-%- '\n(mo/\n(  dy /\n(  yr  ' 
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which  would  produce: 
FINAL 
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DISPLAYS 


Displays  are  sections  of  text  that  the  user  desires  to 
be  set  off  from  the  main  body  of  the  document.  Depending  on 
the  type  of  display,  the  user  ma y  or  ma y  not  wa n t  the 
display  to  be  formatted  by  NROFF .  There  are  several  types 
of  displays: 

1 .  Lists 

2.  Keeps 

a .  Blocks 

b .  Floating 

3 .  Quotes 

4 .  Centered  Blocks 

Each  display  type  is  discussed  in  this  section. 


Lists 


A  list  is  a  single  spaced,  unfilled  display.  Lists 
should  be  used  when  the  user  does  not^  want  the  output  text 
to  be  filled  and  r i gh t - j u s t i f i ed .  One  example  of  material 
that  might  be  placed  in  a  list  is  a  column  of  figures.  A 
list  is  surrounded  by  the  ".(1"  and  " . )  1"  instructions  and 
each  list  entry  is  indented  5  spaces.  For  example: 

The  advantages  of  this  approach  are: 

.(1 

-  the  more  effective  use  of  human  resources 

-  insurance  against  loss  of  personnel 

-  an  improved  training  atmosphere  for  "junior" 
prog  r anrme  r  s 

.  )  1 

This  input  will  be  formatted  as: 

The  advantages  of  this  approach  are: 

-  the  more  effective  use  of  human  resources 

-  insurance  against  loss  of  personnel 

-  an  improved  training  atmosphere  for  "junior" 
prograrrmers 


Keeps 


A  keep  is  a  display  of  text  which  is  kept  on  a  single 
page  is  possible.  Keeps  will  not  be  broken  over  a  page 
boundary  (unlike  lists).  A  diagram  is  an  example  of  the 
type  of  text  the  user  would  probably  put  into  a  keep. 

EMock  Keeps 


Blocks  are  the  basic  kind  of  keep.  Blocks  are  sur¬ 
rounded  by  the  instructions  ".(b"  and  " . ) b " .  For  example: 

.  ( b 

This  is  an  example  of  a  block  keep. 


NAvE 


APPROACH 


Hop-Down  Based  upon  decomposition 
iDesign  by  trial  and  error 

I 

iStructured  Based  upon  decomposition 
IDesign  determined  by  data  flow 

I  or  data  transformations 

I 

.  )b 


This  input  will  be  output  as: 


This  is  an  example  of  a  block  keep. 


I  NAdE 

I 

I  Top -Down 
IDesign 

I 

IStructured 

(Design 

I 

I 


APPROACH 

Based  upon  decomposition 
by  trial  and  error 

Based  upon  decomposition 
determined  by  data  flow 
or  data  transformations 


If  there  is  not  enough  space  on  the  current  page  for  the 
entire  block,  a  new  page  is  started.  To  avoid  leaving  large 
amounts  of  blank  space,  the  user  may  choose  to  split  up  the 
block  into  two  smaller  blocks  or  he  may  choose  to  use  a 
"floating"  keep. 
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F j_oa t_^nq  Keeps 


Floating  keeps  move  relative  to  the  text.  A  floating 
keep  will  appear  at  the  bottom  of  the  current  page  if  there 
is  enough  space;  otherwise,  it  will  appear  at  the  top  of  the 
next  page.  Ma terial  which  will  be  referred  to  within  the 
text  (e.g.,  "see  figure  1")  is  often  used  in  a  floating 
keep.  Floating  keeps  are  surrounded  by  the  instructions 
". (z"  and  ".  )z". 


Quotes 


Often  it  is  desired  to  set  quotes  off  from  the  rest  of 
the  text.  Those  quotes  are  more  indented  than  the  rest  of 
the  text  and  have  quote  marks  around  them  as  the  user 
desires.  These  quotes  are  surrounded  by  the  ".(q"  and  ".)q" 
instructions.  For  example,  the  input: 

•  (q 

"Structured  p  r  og  r  arrmi  ng  is  the  formation  of 
programs  as  hierarchical,  nested  structures 
of  statements  and  objects  of  compu tat i on . " 

•  )q 


generates  as  output: 


"Structured  p  rog  r  arrmi  ng  is  the  formation  of  programs 
as  hierarchical,  nested  structures  of  statements  and 
objects  of  computation." 


Centered  Blocks 


When  the  user  wants  to  center  several  lines  as  a  group, 
rather  than  centering  them  one  line  at  a  time,  it  is  con¬ 
venient  to  use  centered  blocks.  Centered  blocks  are  sur¬ 
rounded  by  the  instructions  ".(c"  and  ".)c".  Centered 
blocks  are  not  keeps  and  may  be  used  in  conjunction  with 
keeps.  By  using  this  facility,  all  the  lines  are  centered 
as  a  unit,  such  that  the  longest  line  is  centered  and  the 
remaining  lines  are  lined  up  around  that  line.  For  example, 
the  input: 


-11- 


.(b 

.  ( c 

engineering  analysis 
s imu  I  a  t ion 
exper i ence  data 
.  )c 
.  )  b 


will  produce : 


engineering  analysis 
s  imu 1  a  t i on 
exper i ence  data 


SPECIAL  PARAGRAPHS 


This  section  describes  the  various  types  of  special 
paragraphs  that  the  user  may  want  to  use  in  document  wr  i  t - 
i  ng . 


Block  Style  Paragraphs 


To  generate  block  style  paragraphs  (  i  .  e •  ,  paragraphs 
that  are  le f t - j u s t  i  f i ed ,  non  -  i ndent ed ) ,  the  user  may  use  the 
".lp"  instruction.  For  example,  the  input: 

.  lp 

A  third  useful  technique  is  the  use  of 
software  tools,  especially  text  editors, 
which  will  save  time  and  effort. 

will  be  output  as : 


A  third  useful  technique  is  the  use  of  software  tools,  espe¬ 
cially  text  editors,  which  will  save  time  and  effort. 


Exdented  Paragraphs 


Exdented  paragraphs  are  those  that  have  the  body 
indented  and  the  first  line  exdented  with  a  label.  These 
paragraphs  are  initiated  by  the  ".ip"  instruction.  For 
examp  le : 
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.  ip  one 

This  is  the  first  paragraph. 

The  second  line  will  line  up  with 
the  first  line  in  this  paragraph. 
.  i  p  two 

This  is  the  second  paragraph. 

This  input  text  will  be  output  as: 


one  This  is  the  first  paragraph.  The  second  line  will  line 
up  with  the  first  line  in  this  paragraph. 

two  This  is  the  second  paragraph. 

The  paragraphs  generated  by  the  ".ip"  instruction  are 
normally  indented  5  spaces.  If  the  label  is  longer  than  the 
space  allocated  for  the  label,  the  ".ip"  instruction  will 
begin  a  new  line  a_ft^£  the  label.  For  example,  the  input: 

. ip  long labe  1 

This  paragraph  has  a  long  label,  therefore 
the  first  character  of  the  paragraph  itself 
will  begin  on  a  new  line. 

will  generate  the  output: 


long  label 

This  paragraph  has  a  long  label,  therefore  the  first 
character  of  the  paragraph  itself  will  begin  on  a  new 
line. 


This  instruction  may  also  be  used  to  generate  alphabet¬ 
ized  paragraphs.  Two  examples  follow: 

•  ip 

a.  This  is  the  first  item. 

Again  the  second  line  will  be  lined 
up  with  the  first  line. 

.ip  [b] 

This  is  the  second  paragraph,  which 
illustrates  a  different  method. 

This  input  will  generate: 


a.  This  is  the  first  item.  Again  the  second  line  will 
be  lined  up  with  the  first  line. 

[b]  This  is  the  second  paragraph,  which  illustrates  a  dif¬ 
ferent  method. 
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Another  variation  of  this  instruction  is  the  ability  to 
put  longlabels  on  the  paragraphs.  This  is  accomplished  by 
adding  a  second  parameter  to  the  ".ip"  instruction.  For 
those  users  who  have  used  the  "-mm"  instructions  on  the  DEC 
11/70,  this  variation  is  similar  to  the  variable  list  capa¬ 
bility.  For  example: 

.ip  1  ong  1  abe  1  10 

This  paragraph  has  a  long  |ahpi  , 
but  the  "10"  parameter  will  cause 
the  paragraph  to  be  indented  10  spaces 
to  allow  space  for  the  longlabel. 

This  input  will  generate  the  following  output: 


longlabel  This  paragraph  has  a  long  label,  but  the  "10" 
parameter  will  cause  the  paragraph  to  be  indented 
10  spaces  to  allow  space  for  the  longlabel. 


Numbered  Paragraphs 


Automatically  numbered  paragraphs  can  be  generated  by 
the  instruction,  ".np".  The  paragraphs  are  numbered  sequen¬ 
tially  from  "1"  and  the  nurrtbering  is  reset  at  the  next 
•PP  »  •  1 P  "  »  or  " . s  h "  instruction.  For  ex  amp  1 e : 

.  np 

Th is  is  the  first  paragraph. 

.  np 

This  is  the  second  paragraph. 

The  second  line  of  this  paragraph  is 
also  lined  up  with  the  other  line. 

This  input  will  be  formatted  as: 


(1)  This  is  the  first  paragraph. 

(2)  This  is  the  second  paragraph.  The  second  line  of  this 
paragraph  is  also  lined  up  with  the  other  line. 


ADVANTED  INSTRUCTIONS 


SECTION  HEADINGS 


Automatically  Numbered  Headings 

Section  numbers  (e.g.,  1.1,  1.2,  1.2.1,  etc.)  can  be 
automatically  generated  by  using  the  ".sh"  macro  instruc¬ 
tion.  The  format  of  this  instruction  is: 

.sh  N  “section  title" 

where  "N"  is  the  depth  of  the  section  number,  that  is,  how 
many  numbers  should  be  in  the  section  number  NROFF  will  gen¬ 
erate.  If  the  user  does  not  want  the  numbered  headings  to 
be  underlined,  it  is  necessary  to  change  a  register  setting 
at  the  beginning  of  the  document: 

•  nr  s f  3 

For  example: 

.nr  s  f  3 

.sh  1  "Section  1" 

•PP 

The  text  of  Section  1. 

•sh  2  "Subsection  1" 

.sh  2  "Subsection  2" 

.sh  1  "Section  2" 

This  is  another  major  section. 

This  input  will  generate: 

1 .  Sect  ion  1 

The  text  of  Section  1. 

1.1.  Subsection  1 

1.2.  Subsect i on  2 

2.  Section  2  This  is  another  major  section. 


Uhnumbered  Headings 

Section  headers  wj_^hout,  automatically  generated  numbers 
can  be  produced  by  using  the  ".uh"  instruction,  whose  format 
i  s : 
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.  uh  "section  title" 


An  example  of  the  use  of  the  unnumbered  section  title  is  the 
section  header  above,  "SECTION  HEADINGS" . 


DELAYED  TEXT 


Delayed  text  is  text  that  is  printed  onJ_^  when  it  is 
explicitly  called  for,  such  as  at  the  end  of  each  chapter. 
There  are  several  types  of  delayed  text: 

1.  Footnotes,  printed  at  the  bottom  of  the  current 
page . 

2.  References,  printed  at  the  end  of  each  chapter 
or  at  the  end  of  the  document. 

3.  Indexes,  delayed  text  accompanied  by  "tags" 
(usually  page  numbers). 


Footnotes 

Footnotes  begin  with  the  ".(f"  instruction  and  end  with 
the  ".)f"  instruction.  NROFF  automatically  maintains  the 
current  footnote  number  and  is  accessed  by  the  user  by  typ¬ 
ing  "  \**"  to  produce  a  footnote  number.  The  number  is 
automatically  incremented  after  every  footnote.  For  exam¬ 
ple,  the  input: 


•  (q 

There  have  been  several  definitions 
of  software  engineering  posed  since  the 
early  1970s. \  *  * 

.(  f 

\**Randall  W.  Jensen 
.  u  1 

Software  Engineering 
Prent i ce -Ha  1 1 ,  Inc.,  1979 
p.9 
.  )f 

•  )q 


will  generate  within  the  document: 

There  have  been  several  definitions  of  software  en¬ 
gineering  posed  since  the  early  1970s. [1] 


[l]Randall  W.  Jensen  Software  Engineering  Prentice-Hall, 
Inc.,  1979  p.9 
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The  footnote  itself  is  appropriately  spaced  and  printed  at 
the  bottom  of  the  same  page  (see  bottom  of  previous  page). 

Note  that  the  footnote  command  details  appear  inside 
the  quote;  this  insures  that  the  footnote  will  appear  on  the 
same  page  as  the  quote. 


Re  f erence  s 


Another  type  of  delayed  text  is  a  reference  list. 
References,  or  delayed  text,  begin  with  the  ".(d"  instruc¬ 
tion  and  end  with  the  ".)d"  instruction.  As  with  footnotes, 
the  delayed  text  instruction  appears  j_n££de  the  quote 
instruction  contents.  To  automatically  generate  reference 
numbers,  the  symbol  is  used  both  at  the  end  of  the 

quote  or  reference  and  at  the  beginning  of  the  reference 
itself.  An  example  follows: 

•  (q 

Software  engineering  is  a  discipline,  rather  than 
a  techno  logy.  \  *// 

.(d 

W/ 

.  u  1 

Software  Eng i nee r i ng : Pr ob 1 ems  &  Future  Development, 
J.  A.  Clapp, 

Mitre  Corp . , 

Prepared  for  Electronic  Systems  Division, 

Nov. , 1974 
.)d 

•  )q 


This  input  will  produce: 

Software  engineering  is  a  discipline,  rather  than  a 
techno  1 ogy  .  [ 1  ] 

To  print  the  delayed  text  (the  reference  details)  when 
desired,  the  ".pd"  instruction  is  used.  When  printed,  the 
reference  will  appear  as  follows: 


[  1  ]  Software  Fn^ _i_n e e £ j_n£ : Problems  &  Future  Deve  1  opment ,  J. 
A.  Clapp,  Mitre  Corp.,  Prepared  for  Electronic  Systems  Divi¬ 
sion,  Nov., 1974 
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Indexes 


»  An  index,  or  table  of  contents,  can  be  automatically 

generated  by  NROFF.  The  entries  that  the  user  chooses  to 
have  in  the  index  are  automatically  saved  by  NROFF  and 
printed  only  when  called  for.  Index  entries  begin  with  the 
(x"  instruction  and  end  with  the  ".)x"  instruction. 

The  .(x  instruction  may  have  a  single  character  argu¬ 
ment  to  specify  the  name  of  the  index;  in  this  way  several 
indicies  may  be  maintained  by  NROFF  simultaneously  to  be 
printed  as  desired.  There  are  several  uses  for  this  abil¬ 
ity,  such  as  a  list  of  tables  or  a  list  of  figures. 

Other  arguments  the  .(x  instruction  may  have  are: 

1.  A  n umb e r ,  which  is  the  value  to  print  as  the 
page  number 

2.  An  unde L5.22L®. »  which  causes  no  page 

number  or  line  of  dots  to  be  printed. 

3.  an  empty  pair  of  quotes,  which  specifies  a 
nu 1 1  page  number . 

Without  a  number  argument,  the  default  page  number 
inserted  in  the  index  will  be  the  page  on  which  the 
section  appears  in  the  document. 

An  example  of  index  generation  follows: 

.  (  x 

Int roduc t  ion 
.  )x 

.  (  X  _ 

Chapter  1 
.  )x 

.(x  4.2 
Chapter  2 
.  )  x 

.(x  "" 

Cone lu  s i on 
.  )x 
.  xp 

This  input  will  generate  the  following  output  after  the 
".xp"  instruction.  Notice  that  the  index  must  be  printed  at 
the  end  of  the  paper,  rather  than  at  the  beginning  where  it 
will  probably  appear  in  the  final  product;  the  pages  will 
have  to  be  physically  rearranged  after  printing. 
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I  n  t  roduc  t  i  on . 1 

Chapter  1 

Chapter  2 . . . 4.2 

Cone lusion . 


OOLUMNED  H  ITPUT 


NROFF  is  also  able  to  handle  a  2-column  mode  of  output. 
Additionally,  the  user  is  able  to  turn  this  mode  of  output 
on  and  off  as  desired. 

The  instruction  ".2c"  tells  NROFF  to  enter  the  2-column 
mode.  This  mode  will  be  in  effect  until  the  ".lc"  instruc¬ 
tion,  to  revert  to  s  i  ng  1  e -c  o  1  urrm  mode,  is  given.  The 
instruction  to  begin  a  new  column  is  ".be".  This  instruc¬ 
tion  begins  a  new  column  on  a  new  page  only  if  necessary, 
rather  than  forcing  a  entire  new  page  if  there  is  space  for 
another  column  on  the  current  page. 

When  the  user  calls  NRDFF  to  format  the  input  (both 
text  and  macro  instructions)  for  2-column  output,  he  must 
also  call  the  2-column  post  processor ,  "col".  This  post 
processor  enables  a  printer  device  without  a  reversable 
forms  feed  capability  to  handle  2-column  output.  The  com¬ 
mand  for  2-column  processing  is: 

nroff  -me  your  f i 1 e | co 1 


or 


nroff  -me  X2HL ill® I co 1  I ca t  -d 


Figure  2  is  a  sample  of  2-column  text  input.  Figure  3 
is  the  resultant  output  after  this  sample  input  has  been 
formatted  by  NRDFF  and  "col". 
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.  ce 

WHAT  TYPES  OF  USERS  NEED  SOFTWARE  ENGINEERING? 

.  sp2 

The  following  sections  are  intended  to  serve  as 
guides  to  the  users  of  the  different  computer  systems 
available  at  DTNSRDC. 

.  sp2 
.  ce 

SMALL /ONE -TIME  APPLICATIONS 

.  sp 

.2c 

Users  with  small  and  one-time  applications,  either 
on  a  strictly  interactive  system  or  on  a  combination 
of  interactive  and  batch,  should  make  use  of  at  least 
two  or  three  of  the  Software  Engineering  techniques 
described  above. 

.pp 

The  first  technique,  documentation,  provides  an 
invaluable  permanent  record  of  a  progranmner /sc  ient  i  st 's 
work . 

Often  a  small  task  is  later  added  to  and  becomes  a 
major  effort,  or  an  intended  one-time  application  is 
used  more  than  once. 

.  be 

A  complete,  permanent  description  of  the  initial 
effort  will  make  the  later  task  easier  and  more 
t  ime  -efficient. 

Likewise,  it  is  helpful  to  have  someone  not 
familiar  with  the  project  read  your  documentation  and 
try  to  follow  the  instructions  provided  for  data 
creation  and  format,  input,  etc. 

Any  misdirection  discovered  at  this  stage  will 
save  later  users  many  hours  of  wasted  effort. 

.  lc 
.pp 

The  second  technique  that  will  be  beneficial 
for  sma  1  1 /one  - 1  i'.ie  applications  is  verification. 


Figure  2  Sample  Text  for  2 -Columned  Output 
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UHAT  TYPES  OF  USERS  NEED  SOFTWARE  ENGINEERING? 


The  following  sections  are  intended  to  serve  as  guides  to 
the  users  of  the  different  computer  systems  available  at 
DTNSRDC. 


SMALL /ONE -TIME  APPLICATIONS 


Users  with  sma  11  and  one¬ 
time  applications,  either  on 
a  strictly  interactive  sys- 
t em  or  o n  a  c omb i n a t i o n  of 
interactive  and  batch, 
should  make  use  of  at  least 
two  or  three  of  the  Software 
Engineering  techniques 
described  above. 

The  first  technique, 
documentation,  provides  an 
invaluable  permanent  record 
of  a  programmer /sc ient i st 's 
work.  Often  a  small  task  is 
later  added  to  and  becomes  a 
major  effort,  or  an  intended 
one-time  application  is  used 
more  than  once. 


A  complete,  permanent 
description  of  the  initial 
effort  will  make  the  later 
task  easier  and  more  time- 
efficient.  Likewise,  it  is 
helpful  to  have  someone  not 
familiar  with  the  project 
read  your  documentation  and 
try  to  follow  the  instruc¬ 
tions  provided  for  data 
creation  and  format,  input, 
etc.  Any  misdirection 
discovered  at  this  stage 
will  save  later  users  many 
hours  of  wasted  effort. 


The  second  technique  that  will  be  beneficial  for 
sma 1 1 /one-t  ime  applications  is  verification. 


Figure  3  Sample  2-Column  Output 
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OTHER  DOCUMENT  COMMANDS 


Although  reports  traditionally  have  the  abstract,  table 
of  contents,  list  of  figures,  etc.  at  the  front  of  the  docu¬ 
ment,  it  is  more  convenient  to  format  and  print  them  last 
when  using  MROFF .  In  this  manner,  entries  (e.g.,  indexes, 
figures,  and  references)  are  collected  throughout  the  paper 
and  then  printed  with  the  correct  formats  and  headers.  The 
following  lists  several  of  these  useful  instructions.  The 
last  section  of  this  guideline  contains  a  sample  document 
which  illustrates  how  several  of  these  instructions  are 
used . 


•  xp  n  -  Print  the  index;  optional  parameter,  "n", 
is  the  index  specified  by  the  user.  This 
instruction  will  print  all  entries  that 
have  been  collected  in  the  "n"  buffer  area 
by  the  ".(x  n"  instruction. 

. pd  -  Print  the  delayed  text.  All  text  that  has 

been  saved  (collected)  via  the  ".(d"  and  *'.)d" 
instructions  is  printed.  This  may  be  useful 
to  print  references,  etc.  at  the  end  of  each 
chapter  or  section,  if  the  user  desires. 

. ++m  h  -  This  instruction  defines  that  section  of  the 
paper  which  is  being  entered.  The  "m" 
parameter  defines  the  section  type  (see  the 
different  types  below).  The  "h"  parameter 
defines  the  new  header  (not  title  but  header). 


Section  Types: 

•  +  +C  -  The  chapter  portion  of  the  paper 

•  +  +A  -  The  appendix  portion  of  the  paper 

•++P  -  The  material  following  this  instruction  is 

the  preliminary  portion  (table  of  content, 
list  of  figures,  etc.)  of  the  paper.  This 
instruction  also  causes  the  page  numbers  to 
be  restarted  from  one  in  lower  case  Roman 
numer  a  1  s . 

.++AB  -  The  abstract  portion  of  the  paper  follows 

this  instruction. 

•++B  -  The  bibliographic  portion  of  the  paper, 

which  will  be  placed  at  the  end,  follows 
this  instruction. 
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Additionally,  the  ".+c"  instruction  may  be  used  to 
define  the  title  for  whichever  separate  section  of  the  paper 
is  being  processed.  An  example  of  these  two  types  of 
instructions  as  they  might  be  used  follows: 

.  +  +B 

. +  cB I BL I OGRAPHV 
...text  of  bibliography... 

.  +  +P 
.  bp 
.  ce 

TABLE  OF  CONTENTS 
...table  of  contents... 
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SAMPLE  NROFF  DOCUMENT 


The  following  text  is  a  sample  document,  which  is  ready 
to  be  input  to  NROFF.  This  sample  incorporates  many  of  the 
macro  instructions,  rules,  and  conventions  discussed  in  this 
guideline  which  are  necessary  to  produce  NROFF  formatted 
text . 

Not.e  that  the  page  numbers  for  this  sample  document  are 
numbered  consistent  with  this  main  document,  rather  than 
beginning  with  "1",  as  they  would  normally  be  numbered  in  a 
separate  document.  Additionally,  note  that  the  Table  of 
Contents  page  that  is  produced  for  this  sample  document  has 
the  Roman  numeral  "i"  as  its  page  number. 
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.he  - 

. fo  'DRAFT *-%- '  \*( td ' 

.  ce 

ABSTRACT 
.  (  x 

ABSTRACT 
.  )x 
.  sp 

•  PP 

This  report  gives  users  of  the  DTNSRDC  computers 
an  overview  of  the  principles  of  software  engineering 
and  describes  various  software  engineering  techniques 
that  users  with  either  large  or  small  applications  would 
find  bene  f  i  c  i  a  1  . 

.  sp2 
.  ce 

BACKGROUND  &  DEFINITION 
.  (  x 

BACKGROUND  &  DEFINITION 
.  )x 
.  sp 

•  PP 

The  term  "Software  Engineering"  was  coined  during  the 
late  1960's  at  a  NATO  Science  Cormnittee  conference. 

Since  then,  many  articles  and  books  have  been 
published  in  an  attempt  to  define  this  approach 
to  producing  and  managing  software. 

.  sp 

•  (q 

"Software  engineering  is  not  just  a  collection  of  tools 
and  techniques,  it  is  ...  a  full-fledged  engineering 
discipline  .  .  .  ".  \*ft 
.(  d 

\  *//  Jensen,  R.  W.  and  C.  C.  Tonies, 

.  u  1 

Software  Engineering, 

Prent i ce -Ha  1 l ,  Inc. 

(1979). 

. )  d 
.  )  q 
.  (q 

"...  the  establishment  and  use  of  sound 
engineering  principles  (methods) 
in  order  to  obtain  economically  software  that 
is  reliable  and  works  on  real  mach  i  ne  s .  "  \  *// 

.(d 

\  Bauer ,  F .  L .  , 

"Software  Engineering," 

.  u  1 

Information  Processing  71, 

PmsterdamsNor th  Holland  Publishing  Co., 
p.  530, 

1972 
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.  )d 

•  )q 

.  sp2 
.  ce 

PURPOSE 

.(x 

PURPOSE 
.  )  x 
.  sp 

•  PP 

High-quality  software  can  be  defined  as  having 
the  following  characteristics: 

.(b 

1.  Reliability  4.  Portability 

2.  Clarity  5.  Ef f i c i ency /Economy 

3 .  Maintainability  6.  Testability 


.  )b 

The  advantages  of  this  approach  are: 

.  ip  a. 

the  more  effective  use  of  human  resources 
.  ip  b. 

a  better  design 
.  ip  c. 

insurance  against  loss  of  personnel 
.  bp 

•  c© 

REFERENCES 
.  (  x 

REFERENCES 
.  )x 
.  sp3 

.  pel 

•  +  +P 

.  bp 

.  ce 

TABLE  OF  CONTENTS 
.  sp3 
.  I  s  2 
.  xp 


The  following  3  pages  of  text  is  the  formatted  output 
which  resulted  from  putting  the  previous  sample  text  through 
hFOFF  (and  the  post  processor,  "col"). 


-26- 


ABSTRACT 


This  report  gives  users  of  the  DTNSRDC  computers  an 
overview  of  the  principles  of  software  engineering  and 
describes  various  software  engineering  techniques  that  users 
with  either  large  or  small  applications  would  find  benefi¬ 
cial. 


BACKGROUND  &  DEFINITION 


The  term  "Software  Engineering"  was  coined  during  the 
late  1960's  at  a  NATO  Science  Conrmittee  conference.  Since 
then,  many  articles  and  books  have  been  published  in  an 
attempt  to  define  this  approach  to  producing  and  managing 
software. 


"Software  engineering  is  not  just  a  collection  of 
tools  and  techniques,  it  is  ...  a  full-fledged  en¬ 
gineering  discipline  ...".[1] 


"...  the  establishment  and  use  of  sound  engineering 
principles  (methods)  in  order  to  obtain  economically 
software  that  is  reliable  and  works  on  real 
mach  ines. "[2] 


PURPOSE 


High-quality  software  can  be  defined  as  having  the  fol¬ 
lowing  characteristics: 


1.  Reliability 

2.  Clarity 

3.  Maintainability 


A .  Portability 

5.  Ef f i c i ency /Economy 

6 .  Testability 


The  advantages  of  this  approach  are: 

a.  the  more  effective  use  of  human  resources 

b.  a  better  design 

c.  insurance  against  loss  of  personnel 
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